09 요청, 응답의 이해 | ✅ 저자: 이유정(박사)

웹 서비스 전체 흐름으로 사용자가 브라우저를 통해 요청하고, 서버에서 처리해 응답을 주는 전체 요청-응답 사이클입니다.

전체 흐름 요약

클라이언트 → Routing → Pydantic Model(검증) → ORM(Model) → DB → 응답

클라이언트 측 Client 사용자의 기기 (예: 컴퓨터, 스마트폰) Browser 사용자 요청을 전달하는 도구 (예: Chrome, Edge) Frontend Server HTML/CSS/JS 등 사용자 인터페이스를 제공하는 서버 즉, 사용자가 웹사이트에서 검색하거나 버튼을 클릭하면 이 영역에서 요청(Request)이 시작돼요.

---

Backend Server : FastAPI로 만든 API 코드들이 실행되는 공간 전체 구조에서 Backend Server 역할 astAPI 백엔드 서버의 역할은 클라이언트로부터 들어오는 요청을 받아 처리하는 것입니다. 개발 중에는 Uvicorn과 같은 ASGI 서버를 사용하여 FastAPI 애플리케이션을 직접 실행하고 테스트합니다.

하지만 실제 서비스를 배포할 때는 Nginx나 Apache 같은 웹 서버(Reverse Proxy) 를 앞단에 두고, 그 뒤에 Uvicorn, Gunicorn 등의 ASGI 서버와 FastAPI를 연동하여 운영합니다. 웹 서버는 정적 파일 제공, 로드 밸런싱, 보안 설정 등의 역할을 하며, 클라이언트 요청을 FastAPI 앱으로 안전하게 전달하는 중간 다리 역할을 합니다.

요청 받기 클라이언트(브라우저)로부터 요청을 받음 (예: /search?q=파스타) 검증 및 처리 Pydantic으로 파라미터 검증 후 내부 로직 실행 데이터 요청/변경 DB에 접근해서 데이터를 꺼내거나 저장 응답 보내기 처리 결과를 JSON 형태로 다시 클라이언트에게 전달

🔴 Backend Server
└── Routing Logic  → 어떤 URL로 요청 왔는지 판단
└── Pydantic Model → 데이터 검증 (유효한지 확인)
└── ORM(Model/Session) → DB에서 데이터 가져오고 저장

---

라우팅 로직 : FastAPI가 요청을 어떻게 처리할지 결정하는 첫 관문 Pydantic Model 이란? 입력값을 검증하고 응답 형태를 정의하는 데이터 모델로, FastAPI에서 사용자의 요청 데이터를 안전하게 처리하기 위한 도구입니다. JSON 데이터를 파이썬 객체로 바꿔주고, 동시에 유효성 검사를 해주는 구조체 같은 클래스"입니다.
주로 POST, PUT 요청에서 클라이언트가 보내는 body 데이터를 처리할 때 사용합니다. 들어오는 값을 미리 검열해서 잘못된 값은 걸러주는 필터 역할입니다.

ORM (Model) 검증된 데이터를 기반으로 실제 DB와 연결된 ORM 모델에 전달됩니다.

• 예: Restaurant.objects.filter(name=q) → DB에서 결과 가져옴
• 이 ORM은 SQL 대신 파이썬 코드로 DB를 다루게 해줍니다. 즉, “정상적인 요청을 DB에 전달하고, 결과를 받아오는 역할”

다이어그램을 토대로 코드 살펴보기

from fastapi import FastAPI
from pydantic import BaseModel

# FastAPI 앱 생성
app = FastAPI()

# 요청/응답용 Pydantic 모델 정의
class Item(BaseModel):
    name: str
    description: str | None = None # null=True, blank=True
    price: float
    tax: float | None = None # | None = None이 들어가면 필수값이 아님

# POST 요청 처리 API
@app.post("/items/")
async def create_item(item: Item):
    return item

item: Item은 FastAPI에서 요청(request) 본문으로 들어온 JSON 데이터를 Item이라는 Pydantic 모델로 자동 변환하겠다는 뜻이에요.

전체 흐름을 의사코드로 해석

1. FastAPI 라이브러리에서 웹 API 서버를 만들 수 있는 도구(FastAPI)호출
2. Pydantic 라이브러리에서 데이터 형식을 검증해주는 도구(BaseModel)호출

3. 웹 API 서버를 생성한다 (FastAPI 객체 만들기)

4. 클라이언트가 보내는 데이터 형식을 정의한다
   - 이 데이터는 상품(Item)에 대한 정보이다
   - 다음과 같은 필드를 가진다:
     - name: 반드시 있어야 하는 문자열
     - description: 없어도 되는 문자열
     - price: 반드시 있어야 하는 숫자 (소수 포함 가능)
     - tax: 없어도 되는 숫자 (소수 포함 가능)

5. 클라이언트가 /items/ 주소로 POST 요청을 보냈을 때 실행될 API를 만든다
   - 요청 본문(body)에 있는 데이터를 Item 형식으로 받는다
   - 받은 데이터를 그대로 응답(response)으로 돌려준다

---

실습해보기: "클라이언트가 보낸 데이터를 FastAPI 서버가 어떻게 받는지" 와
"그 데이터를 어떻게 자동으로 검사하고 응답까지 처리하는지" 를 배우기 위한 코드

📦 1. 클라이언트가 물건을 보낸다 (요청 = Request)

• 예를 들어 쇼핑몰 웹사이트에서 "새 상품 등록" 버튼을 누르면,
• {"name": "vitamin", "price": 2500} 같은 데이터(상품정보) 가 서버로 전송돼요.

🧰 2. 서버는 그 데이터를 검사해야 한다

• 상품 이름이 빈칸이면 안되고, 가격이 숫자가 아니면 안 돼요.
• 이걸 사람이 직접 검사하는 게 아니라, Pydantic이라는 도구가 자동으로 검사해줘요. 이걸 "요청 데이터 유효성 검사" 라고 해요.

🎁 3. 서버는 그 데이터를 받아서 처리하고 응답한다

• 잘 들어온 데이터면 그대로 저장하거나 다시 응답해줘요.
• 에러가 있으면 "어떤 게 잘못됐는지" 클라이언트에게 알려줘요.

사용자가 보내는 데이터를 안전하게 받고, 형식을 자동으로 검사하고,
응답을 잘 돌려주는 구조를 이해하고 직접 실습해보는 것이 이 예제의 핵심입니다.

# item.py
from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

# 요청 및 응답으로 사용할 모델 정의
class Item(BaseModel):
    name: str
    description: str | None = None  # 필수가 아님
    price: float
    tax: float | None = None        # 필수가 아님

# POST 요청 처리
@app.post("/items/")
async def create_item(item: Item):
    return {
        "message": "Item received successfully!",
        "item_data": item
    }

실행

uvicorn item:app --reload

Swagger UI

http://127.0.0.1:8000/docs

POST /items/ 클릭 → Try it out

요청 예시 (성공 케이스)

{
  "name": "vitamin",
  "description": "Apple vitamin",
  "price": 2500.0,
  "tax": 200.0
}

응답 예시 (200 OK)

{
  "message": "Item received successfully!",
  "item_data": {
    "name": "vitamin",
    "description": "Apple vitamin",
    "price": 2500.0,
    "tax": 200.0
  }
}

실패 케이스 실습(필수 누락후 테스트)

{
  "name": "vitamin",
  "description": "Apple vitamin"
}

응답 (422 Unprocessable Entity)

```json
{
  "detail": [
    {
      "type": "json_invalid",
      "loc": [
        "body",
        40 
      ],
      "msg": "JSON decode error",
      "input": {},
      "ctx": {
        "error": "Expecting value"
      }
    }
  ]
}

FastAPI에서 "loc": ["body", 40] 라고 나왔다면, 요청 바디(JSON 문자열) 안에서 40번째 문자 위치쯤에서 문제가 생겼다는 뜻입니다. 40에 의미는 문자열에서 공백, 줄바꿈 포함하여 문자 수 즉 에러의 위치입니다.